/*
// Licensed to Julian Hyde under one or more contributor license
// agreements. See the NOTICE file distributed with this work for
// additional information regarding copyright ownership.
//
// Julian Hyde licenses this file to you under the Apache License,
// Version 2.0 (the "License"); you may not use this file except in
// compliance with the License. You may obtain a copy of the License at:
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
 */
package org.olap4j.query;

import org.olap4j.mdx.ParseTreeNode;
import org.olap4j.metadata.Dimension;
import org.olap4j.metadata.MetadataElement;

import java.util.List;

/**
 * A selection of members from an OLAP dimension hierarchy. The selection is a conceptual list of members from a given
 * hierarchy. Once a selection object is created, one can decide to include or exclude this selection of members from
 * the resulting query.
 * 
 * <p>
 * Concrete subclasses of this represent a real selection. Selections include things such as 'children of', 'siblings
 * of', 'descendents of' etc.
 * 
 * <p>
 * This class is different from a {@link org.olap4j.metadata.Member} because it represents an abstract member selection
 * (e.g. children of widget' that may not represent any members whereas a Member represents a single member that is
 * known to exist.
 * 
 * @author jdixon, jhyde, Luc Boudreau
 * @since May 30, 2007
 */
public interface Selection extends QueryNode {

	/**
	 * Unique name of the selection root.
	 * 
	 * @return The unique OLAP name of the selection root.
	 */
	String getUniqueName();

	/**
	 * Visitor pattern-like function to convert the selection into a ParseTreeNode. Typical implementation should be:<br/>
	 * <code>Olap4jNodeConverter.toOlap4j(member, operator);</code>
	 * 
	 * @return A parse tree node of the selection.
	 */
	ParseTreeNode visit();

	/**
	 * Parent Dimension of the root selection element.
	 * 
	 * @return A dimension object.
	 */
	Dimension getDimension();

	/**
	 * Returns the root selection element of this selection.
	 * 
	 * @return The root metadata object.
	 */
	MetadataElement getRootElement();

	/**
	 * The selection context includes selections from other dimensions that help determine the entire context of a
	 * selection, so drill down is possible.
	 * 
	 * @return list of selections
	 */
	List<Selection> getSelectionContext();

	void addContext(Selection selection);

	void removeContext(Selection selection);

	Operator getOperator();

	/**
	 * Set the selection operator to use.
	 * 
	 * @throws IllegalArgumentException
	 *             if the operator cannot be used on the root selection member.
	 * @param operator
	 *            Operator to apply on the selection.
	 */
	void setOperator(Operator operator);

	/**
	 * Defines which selection operators are allowed, relative to a root member.
	 */
	public enum Operator {
		/**
		 * Only the root member will be selected.
		 */
		MEMBER,
		/**
		 * All members of Level will be selected (LevelSelection only)
		 */
		MEMBERS,
		/**
		 * Only the children of the root member will be selected. This excludes the root member itself.
		 * <p>
		 * Implemented via the MDX .Children member property.
		 */
		CHILDREN,
		/**
		 * The root member will be selected along with all it's children.
		 */
		INCLUDE_CHILDREN,
		/**
		 * Will select the root member along with all it's siblings.
		 * <p>
		 * Implemented via the MDX .Siblings member property.
		 */
		SIBLINGS,
		/**
		 * Selects the set of the ascendants of a specified member, including the member itself.
		 * <p>
		 * Implemented via the MDX Ascendants() function.
		 */
		ANCESTORS,
		/**
		 * Selects the set of the descendants of a specified member, including the member itself.
		 * <p>
		 * Implemented via the MDX Descendants() function.
		 */
		DESCENDANTS;
	}
}

// End Selection.java
